openapi: 3.0.0
info:
  title: User API
  description: Javaboss example User API
  termsOfService: http://www.javaboss.it
  contact:
    name: Massimo Romano
    url: http://massimoromano.altervista.org/
    email: admin@javaboss.it
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
  - url: http://www.javaboss.it/prod/v1
    description: Production environment
  - url: http://www.javaboss.it/test/v1
    description: Test environment

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
     
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://www.javaboss.it/.well-known/openid-configuration
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.javaboss.it/oauth/authorize
          tokenUrl: https://www.javaboss.it/oauth/token
          scopes:
            read_user: Grants read access
            write_user: Grants write access
            admin: Grants access to admin operations
  
security: 
  - BasicAuth: []
  - OAuth2: 
    - read_user
    - write_user
  - OpenID: 
    - read_user
    - write_user
    
paths:
  /user/{id}:
    parameters: 
      - name: id
        in: path
        required: true
        description: Identificativo univoco dell'utente
        schema:
          type : integer
          format: int64
          minimum: 1
    get:
      summary: Recupera le informazioni utente
      description: Consente di recuperare le informazioni associate ad un utente conoscendo il relativo identificativo.
      operationId: getUserById
      externalDocs:
        description: Moggiori informazioni possono essere recuperate al link seguente
        url: https://www.javaboss.it/specifica-openapi
      tags: [Gestione utenti]
      servers: 
        - url: http://www.javaboss.it/preprod/v1
          description: Server preproduzione
      security: 
        - BearerAuth: []
      responses:
        200:
          description: Utente recuperato
          headers:
            X-Custom-Header:
              description: A custom header
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        400:
          description: L'ID fornito è invalido (not a number).
        404:
          description: Utente non trovato.
        default:
          description: Error generico
            
    patch:
      summary: Aggiorna le informazioni utente
      description: Consente di aggiornare le informazioni associate ad un utente conoscendo il relativo identificativo.
      operationId: updateUserById
      externalDocs:
        description: Moggiori informazioni possono essere recuperate al link seguente
        url: https://www.javaboss.it/specifica-openapi
      tags: [Gestione utenti]
      requestBody:
        description: Valori che devono essere aggiornati
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        200:
          description: Utente aggiornato correttamente
        400:
          description: L'ID fornito è invalido (not a number).
        404:
          description: Utente non trovato.
        default:
          description: Error generico